home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / open.n < prev    next >
Text File  |  1994-09-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. open(n)               Tcl Built-In Commands                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      open - Open a file
  12.  
  13. SYNOPSIS
  14.      open _f_i_l_e_N_a_m_e ?_a_c_c_e_s_s? ?_p_e_r_m_i_s_s_i_o_n_s?                          |
  15. _________________________________________________________________
  16.  
  17.  
  18. DESCRIPTION
  19.      This command opens a file and returns an identifier that may
  20.      be  used  in future invocations of commands like read, puts,
  21.      and close.  _F_i_l_e_N_a_m_e gives the name of the file to open;  if
  22.      it  starts with a tilde then tilde substitution is performed
  23.      as described for Tcl_TildeSubst.  If the first character  of
  24.      _f_i_l_e_N_a_m_e  is ``|'' then the remaining characters of _f_i_l_e_N_a_m_e
  25.      are treated as a command pipeline to  invoke,  in  the  same
  26.      style as for exec.  In this case, the identifier returned by
  27.      open may be used to write to the  command's  input  pipe  or
  28.      read from its output pipe.
  29.  
  30.      The _a_c_c_e_s_s argument indicates the way in which the file  (or
  31.      command pipeline) is to be accessed.  It may take two forms,  |
  32.      either a string in the form that  would  be  passed  to  the  |
  33.      fopen library procedure or a list of POSIX access flags.  It  |
  34.      defaults to ``r''.  In the first form _a_c_c_e_s_s may have any of  |
  35.      the following values:
  36.  
  37.      r              Open the file for reading only; the file must
  38.                     already exist.
  39.  
  40.      r+             Open the file for both reading  and  writing;
  41.                     the file must already exist.
  42.  
  43.      w              Open the file for writing only.  Truncate  it
  44.                     if  it exists.  If it doesn't exist, create a
  45.                     new file.
  46.  
  47.      w+             Open the file for reading and writing.  Trun-
  48.                     cate  it  if it exists.  If it doesn't exist,
  49.                     create a new file.
  50.  
  51.      a              Open the file for  writing  only.   The  file
  52.                     must  already  exist,  and  the file is posi-
  53.                     tioned so that new data is  appended  to  the
  54.                     file.
  55.  
  56.      a+             Open the file for reading  and  writing.   If
  57.                     the  file  doesn't  exist, create a new empty
  58.                     file.  Set the initial  access  position   to
  59.                     the end of the file.
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. open(n)               Tcl Built-In Commands                   7.0
  71.  
  72.  
  73.  
  74.      In the second form, _a_c_c_e_s_s consists of a list of any of  the  |
  75.      following  flags, all of which have the standard POSIX mean-  |
  76.      ings.  One of the flags must be  either  RDONLY,  WRONLY  or  |
  77.      RDWR.                                                         |
  78.  
  79.      RDONLY                                                             ||
  80.                     Open the file for reading only.                |
  81.  
  82.      WRONLY                                                             ||
  83.                     Open the file for writing only.                |
  84.  
  85.      RDWR                                                               ||
  86.                     Open the file for both reading and writing.    |
  87.  
  88.      APPEND                                                             ||
  89.                     Set  the  file pointer to the end of the file  |
  90.                     prior to each write.                           |
  91.  
  92.      CREAT                                                              ||
  93.                     Create  the  file if it doesn't already exist  |
  94.                     (without this flag it is  an  error  for  the  |
  95.                     file not to exist).                            |
  96.  
  97.      EXCL                                                               ||
  98.                     If  CREAT  is  specified  also,  an  error is  |
  99.                     returned if the file already exists.           |
  100.  
  101.      NOCTTY                                                             ||
  102.                     If  the  file is a terminal device, this flag  |
  103.                     prevents the file from becoming the  control-  |
  104.                     ling terminal of the process.                  |
  105.  
  106.      NON-  |
  107.                     BLOCK                                                           ||
  108.                     Prevents  the  process  from  blocking  while  |
  109.                     opening  the file.  For details refer to your  |
  110.                     system  documentation  on  the  open   system  |
  111.                     call's O_NONBLOCK flag.                        |
  112.  
  113.      TRUNC                                                              ||
  114.                     If  the  file  exists it is truncated to zero  |
  115.                     length.                                        |
  116.  
  117.      If a new file is created as part of opening it,  _p_e_r_m_i_s_s_i_o_n_s  |
  118.      (an integer) is used to set the permissions for the new file  |
  119.      in conjunction with the process's file mode  creation  mask.  |
  120.      _P_e_r_m_i_s_s_i_o_n_s defaults to 0666.
  121.  
  122.      If a file is opened for both reading and writing  then  seek
  123.      must  be  invoked  between a read and a write, or vice versa
  124.      (this restriction does not apply to command pipelines opened
  125.      with  open).  When _f_i_l_e_N_a_m_e specifies a command pipeline and
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. open(n)               Tcl Built-In Commands                   7.0
  137.  
  138.  
  139.  
  140.      a write-only access is used, then standard output  from  the
  141.      pipeline  is  directed to the current standard output unless
  142.      overridden by the command.  When _f_i_l_e_N_a_m_e specifies  a  com-
  143.      mand  pipeline and a read-only access is used, then standard
  144.      input from the pipeline is taken from the  current  standard
  145.      input unless overridden by the command.
  146.  
  147.  
  148. KEYWORDS
  149.      access mode, append,  controlling  terminal,  create,  file,
  150.      non-blocking, open, permissions, pipeline, process
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.